This document covers the operation of the HELP«»TEXT program. This program is designed to demonstrate the use and coding (in Aztec C) of an on-line help facility, such as is provided with Multiplan™. HELP«»TEXT is a public-domain program which may be distributed freely, as long as proper credit is given to the original author; the program may not be sold.
If you make any improvements to the original code of the program, I would very much like to receive a copy of them. I have used the code from this program in a commercial product that I'm doing for Harrison Systems, and it works well.
This program is intended more for developers or hackers than regular Mac users.
Recommended companion program: Edit
Program operation.
Basically, you will be required to edit text files that contain the help messages that you wish to use. Don't worry if they go over the edge of the help box; you can either change the size of the help box with the aid of the Resource Editor, or you can alter the text file. Using this program, you will convert the text file into a resource of type 'HELP', which the program can read. Feel free to experiment with the existing help resources provided in the file 'HT.Help'.
Once you have a text file, to convert it, execute the 'TEXT » HELP" command. You will be presented with a Standard File dialog with all of the 'TEXT' type files on the disk; choose the one you wish to convert and hit 'Open' (Note: the original text file is merely read; it is not altered in any way when you are converting it to a 'HELP' resource). You will then be asked to name the file to save the HELP resource in. If you choose a filename that already exists, you will get the message 'Replace existing "foo"?'. This is not a factor here since we will be writing only a single resource, and not replacing the entire data fork of a file. After this step, another dialog will appear requesting that you give a number and an (optional) name to the resource about to be written. If a resource with the given number already exists, you will be asked if you wish to overwrite it or cancel the operation. If you continue, the conversion will proceed until an error occurs (in which case you will be presented with an alert box explaining the error), or the conversion is successfully completed.
The reverse operation is equally simple. Assume that you have a HELP resource you wish to change. If you don't have the original TEXT file, don't panic. Just use the "HELP » TEXT" command. This will retrieve a HELP resource from a given file and write it to a vanilla text file, which you can then edit. The process is as follows: after choosing the command, a Standard File dialog will appear asking you to select which file to read the HELP resource from. All available files will be listed, because we are not dependent upon a particular type of file, and we don't use a 'filterProc' to determine only those files that have HELP resources. Once you have chosen a file to read from, you will be asked to name the text file to write to. If the file already exists, you may overwrite it or cancel the operation. You will then be asked to give the resource number to read from. If all goes well, you will get a message to that effect. Otherwise, an error alert will pop up explaining what happened.
Technical points.
When the text of the help message is displayed, it is read into a TextEdit handle, to make its manipulation easier. It is displayed without word wrap. It is displayed in Helvetica-12. All of these factors can be changed if you have a way to recompile the original code.
The 'help titles' displayed in the 'About...' box are drawn with 'DrawString'; therefore, if they are wider than the box they are in, they will be drawn over parts of the scroll bar. Don't panic, just widen the box with the aid of the Resource Editor.
Since this program uses TextEdit and not CoreEdit, tabs are not handled.
You can use MacWrite instead of Edit, but you must remember not to use tabs and you must save the file in 'TEXT only' format!
File & resource sizes are limited to 32K.
This program was written in Aztec C68K. I tried to make it as vanilla as possible, but if you have any questions, just drop me a note.
One possible problem in converting it to another C compiler is that Aztec C's 'int' is only 16 bits, instead of the 32 that you would expect. For this reason, just change all of my 'int' declarations to 'short'.
